﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Creating a view model with a model and mappings</title>
  <keywords>
    <keyword translate="true">ModelAttribute</keyword>
    <keyword translate="true">Models</keyword>
    <keyword translate="true">MVVM</keyword>
    <keyword translate="true">View models</keyword>
    <keyword translate="true">ViewModelBase</keyword>
    <keyword translate="true">ViewModelToModelAttribute</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Creating a view model with a model and mappings</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">During of the use of the MVVM pattern, we noticed that lots and lots of developers have a model, and map the values of the model to all properties of the view model. When the UI closes, the developers map all the properties back to the model. All this redundant code is not necessary when using the view models of Catel.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">In Catel, we have created attributes that allow you to define a property as a model. A model is a property that a part of the view model represents to the user. A view model might have multiple models if it is a combination of several models.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To use the mapping features, the following attributes are very important:</text></para>
    <list id="112" type="ul" listtype="bullet" formatstring="&#183;" format-charset="SYMBOL_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Symbol; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ModelAttribute" styleclass="Normal (list)" translate="true">ModelAttribute</link><text styleclass="Normal (list)" translate="true"> - declare a model in a view model</text></li>
      <li styleclass="Normal (list)"><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ViewModelToModelAttribute" styleclass="Normal (list)" translate="true">ViewModelToModelAttribute</link><text styleclass="Normal (list)" translate="true"> - declare a mapping from a view model property to a model property</text></li>
    </list>
    <para styleclass="Heading2"><text styleclass="Heading2" translate="true">Code snippets</text></para>
    <list id="113" type="ul" listtype="bullet" formatstring="&#183;" format-charset="SYMBOL_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Symbol; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">vm - declare a view model</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">vmpropmodel - declare a property as model on a view model</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">vmpropviewmodeltomodel - declare a property as a pass-through property on a view model</text></li>
    </list>
    <para styleclass="Heading2"><text styleclass="Heading2" translate="true">Explanation</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Defining a model is very simple, you only have to decorate your property with the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ModelAttribute" styleclass="Normal" translate="true">ModelAttribute</link><text styleclass="Normal" translate="true">:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Gets or sets the shop.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">[Model]</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> IShop Shop</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;get { </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">return</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> GetValue&lt;IShop&gt;(ShopProperty); }</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">private</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> set { SetValue(ShopProperty, value); }</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Register the Shop property so it is known in the class.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">static</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">readonly</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> PropertyData ShopProperty = RegisterProperty(&quot;Shop&quot;, </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">typeof</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(IShop));</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Using the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ModelAttribute" styleclass="Normal" translate="true">ModelAttribute</link><text styleclass="Normal" translate="true"> is very powerful. Basically, this is the extended functionality in the view model. If the model supports </text><text styleclass="Normal" style="font-style:italic;" translate="true">IEditableObject</text><text styleclass="Normal" translate="true">, </text><text styleclass="Normal" style="font-style:italic;" translate="true">BeginEdit </text><text styleclass="Normal" translate="true">is automatically called in the initializatiopn of the view model. When the view model is canceled, the </text><text styleclass="Normal" style="font-style:italic;" translate="true">CancelEdit</text><text styleclass="Normal" translate="true"> is called so the changes are undone.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">When a model is defined, it is possible to use the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ViewModelToModelAttribute" styleclass="Normal" translate="true">ViewModelToModelAttribute</link><text styleclass="Normal" translate="true">, as you can see in the code below:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Gets or sets the name of the shop.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">[ViewModelToModel(&quot;Shop&quot;)]</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> Name</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;get { </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">return</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> GetValue&lt;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&gt;(NameProperty); }</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160;set { SetValue(NameProperty, value); }</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// Register the Name property so it is known in the class.</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">/// &lt;/summary&gt;</text><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">static</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">readonly</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> PropertyData NameProperty = RegisterProperty(&quot;Name&quot;, </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">typeof</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">));</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ViewModelToModelAttribute" styleclass="Normal" translate="true">ViewModelToModelAttribute</link><text styleclass="Normal" translate="true"> in the code example above automatically maps the view model </text><text styleclass="Normal" style="font-style:italic;" translate="true">Name </text><text styleclass="Normal" translate="true">property to the </text><text styleclass="Normal" style="font-style:italic;" translate="true">Shop.Name</text><text styleclass="Normal" translate="true"> property. This way, you don’t have to manually map the values from and to the model. Another nice effect is that the view model automatically validates all objects defined using the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ModelAttribute" styleclass="Normal" translate="true">ModelAttribute</link><text styleclass="Normal" translate="true">, and all field and business errors mapped are automatically mapped to the view model.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Summarized, the model and </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_ViewModelToModelAttribute" styleclass="Normal" translate="true">ViewModelToModel</link><text styleclass="Normal" translate="true"> attributes make sure no duplicate validation and no manual mappings are required.</text></para>
  </body>
</topic>
